home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIUpdateService.idl < prev    next >
Encoding:
Text File  |  2006-05-08  |  16.3 KB  |  506 lines
  1. /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Application Update Service
  16.  *
  17.  * The Initial Developer of the Original Code is Google Inc.
  18.  * Portions created by the Initial Developer are Copyright (C) 2005
  19.  * the Initial Developer. All Rights Reserved.
  20.  *
  21.  * Contributor(s):
  22.  *  Ben Goodger <ben@mozilla.org>
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #include "nsISupports.idl"
  39.  
  40. interface nsIDOMDocument;
  41. interface nsIDOMElement;
  42. interface nsIDOMWindow;
  43. interface nsIRequest;
  44. interface nsIRequestObserver;
  45. interface nsISimpleEnumerator;
  46. interface nsITimerCallback;
  47. interface nsIXMLHttpRequest;
  48.  
  49. /**
  50.  * An interface that describes an object representing a patch file that can
  51.  * be downloaded and applied to a version of this application so that it
  52.  * can be updated.
  53.  */
  54. [scriptable, uuid(56863a67-bd69-42de-9f40-583e625b457d)]
  55. interface nsIUpdatePatch : nsISupports
  56. {
  57.   /**
  58.    * The type of this patch:
  59.    * "partial"      A binary difference between two application versions
  60.    * "complete"     A complete patch containing all of the replacement files
  61.    *                to update to the new version
  62.    */
  63.   attribute AString type;
  64.  
  65.   /**
  66.    * The URL this patch was being downloaded from
  67.    */
  68.   attribute AString URL;
  69.  
  70.   /**
  71.    * The hash function to use when determining this file's integrity
  72.    */
  73.   attribute AString hashFunction;
  74.  
  75.   /**
  76.    * The value of the hash function named above that should be computed if
  77.    * this file is not corrupt.
  78.    */
  79.   attribute AString hashValue;
  80.   
  81.   /**
  82.    * The size of this file, in bytes. 
  83.    */
  84.   attribute unsigned long size;
  85.  
  86.   /**
  87.    * The state of this patch
  88.    */
  89.   attribute AString state;
  90.  
  91.   /**
  92.    * true if this patch is currently selected as the patch to be downloaded and
  93.    * installed for this update transaction, false if another patch from this
  94.    * update has been selected. 
  95.    */
  96.   attribute boolean selected;
  97.  
  98.   /**
  99.    * Serializes this patch object into a DOM Element
  100.    * @param   updates
  101.    *          The document to serialize into
  102.    * @returns The DOM Element created by the serialization process
  103.    */
  104.   nsIDOMElement serialize(in nsIDOMDocument updates);
  105. };
  106.  
  107. /**
  108.  * An interface that describes an object representing an available update to
  109.  * the current application - this update may have several available patches
  110.  * from which one must be selected to download and install, for example we
  111.  * might select a binary difference patch first and attempt to apply that, 
  112.  * then if the application process fails fall back to downloading a complete
  113.  * file-replace patch. This object also contains information about the update
  114.  * that the front end and other application services can use to learn more 
  115.  * about what is going on.
  116.  */
  117. [scriptable, uuid(b0fb539e-f4ab-4ea1-bd75-e6d2813e5fc1)]
  118. interface nsIUpdate : nsISupports
  119. {
  120.   /**
  121.    * The type of update:
  122.    *   "major"  A major new version of the Application
  123.    *   "minor"  A minor update to the Application (e.g. security update)
  124.    */
  125.   attribute AString type;
  126.  
  127.   /**
  128.    * The name of the update, or "<Application Name> <Update Version>"
  129.    */
  130.   attribute AString name;
  131.  
  132.   /**
  133.    * The Application version of this update. 
  134.    */
  135.   attribute AString version;
  136.  
  137.   /**
  138.    * The Addon version of this update. Used by the Extension System to track 
  139.    * compatibility of installed addons with this update. 
  140.    */
  141.   attribute AString extensionVersion;
  142.  
  143.   /**
  144.    * The Build ID of this update. Used to determine a particular build, down
  145.    * to the hour, minute and second of its creation. This allows the system
  146.    * to differentiate between several nightly builds with the same |version|
  147.    * for example. 
  148.    */
  149.   attribute AString buildID;
  150.  
  151.   /**
  152.    * The URL to a page which offers details about the content of this 
  153.    * update. Ideally, this page is not the release notes but some other page
  154.    * that summarizes the differences between this update and the previous,
  155.    * which also links to the release notes.
  156.    */
  157.   attribute AString detailsURL;
  158.  
  159.   /**
  160.    * The URL to a HTML fragment that contains a license for this update. If
  161.    * this is specified, the user is shown the license file after they choose
  162.    * to install the update and they must agree to it before the download 
  163.    * commences.
  164.    */
  165.   attribute AString licenseURL;
  166.  
  167.   /**
  168.    * The URL to the Update Service that supplied this update.
  169.    */
  170.   attribute AString serviceURL;
  171.  
  172.   /**
  173.    * Whether or not the update being downloaded is a complete replacement of
  174.    * the user's existing installation or a patch representing the difference
  175.    * between the new version and the previous version.
  176.    */
  177.   attribute boolean isCompleteUpdate;
  178.  
  179.   /**
  180.    * Whether or not the update is a security update or not. If this is true, 
  181.    * then we present more serious sounding user interface messages to the 
  182.    * user. 
  183.    */
  184.   attribute boolean isSecurityUpdate;
  185.  
  186.   /**
  187.    * When the update was installed.
  188.    */
  189.   attribute long long installDate;
  190.  
  191.   /**
  192.    * A message associated with this update, if any.
  193.    */
  194.   attribute AString statusText;
  195.  
  196.   /**
  197.    * The currently selected patch for this update.
  198.    */
  199.   readonly attribute nsIUpdatePatch selectedPatch;
  200.  
  201.   /**
  202.    * The state of the selected patch:
  203.    *   "downloading"       The update is being downloaded.
  204.    *   "pending"           The update is ready to be applied.
  205.    *   "applying"          The update is being applied.
  206.    *   "succeeded"         The update was successfully applied.
  207.    *   "download-failed"   The update failed to be downloaded.
  208.    *   "failed"            The update failed to be applied.
  209.    */
  210.   attribute AString state;
  211.  
  212.   /**
  213.    * A numeric error code that conveys additional information about the state
  214.    * of a failed update.  If the update is not in the "failed" state, then this
  215.    * value is zero.
  216.    *
  217.    * TODO: Define typical error codes (for now, see updater/errors.h)
  218.    */
  219.   attribute long errorCode;
  220.  
  221.   /**
  222.    * The number of patches supplied by this update.
  223.    */
  224.   readonly attribute unsigned long patchCount;
  225.  
  226.   /**
  227.    * Retrieves a patch. 
  228.    * @param   index
  229.    *          The index of the patch to retrieve.
  230.    * @returns The nsIUpdatePatch at the specified index.
  231.    */
  232.   nsIUpdatePatch getPatchAt(in unsigned long index);
  233.  
  234.   /**
  235.    * Serializes this update object into a DOM Element
  236.    * @param   updates
  237.    *          The document to serialize into
  238.    * @returns The DOM Element created by the serialization process
  239.    */
  240.   nsIDOMElement serialize(in nsIDOMDocument updates);
  241. };
  242.  
  243. /**
  244.  * An interface describing an object that listens to the progress of an update
  245.  * check operation. This object is notified as the check continues, finishes
  246.  * and if it has an error. 
  247.  */
  248. [scriptable, uuid(8cbceb6e-8e27-46f2-8808-444c6499f836)]
  249. interface nsIUpdateCheckListener : nsISupports
  250. {
  251.   /**
  252.    * Called every time there is a progress notification loading the Update
  253.    * Service file.
  254.    * @param   request
  255.    *          The nsIXMLHttpRequest handling the update check.
  256.    * @param   position
  257.    *          The current byte downloaded
  258.    * @param   totalSize
  259.    *          The total number of bytes that have to be downloaded
  260.    */
  261.   void onProgress(in nsIXMLHttpRequest request, 
  262.                   in unsigned long position,
  263.                   in unsigned long totalSize);
  264.  
  265.   /**
  266.    * The update check was completed. 
  267.    * @param   request
  268.    *          The nsIXMLHttpRequest handling the update check.
  269.    * @param   updates
  270.    *          An array of nsIUpdate objects listing available updates.
  271.    * @param   updateCount
  272.    *          The size of the |updates| array.
  273.    */
  274.   void onCheckComplete(in nsIXMLHttpRequest request, 
  275.                        [array, size_is(updateCount)] in nsIUpdate updates,
  276.                        in unsigned long updateCount);
  277.  
  278.   /**
  279.    * An error occurred while loading the remote update service file. 
  280.    * @param   request
  281.    *          The nsIXMLHttpRequest handling the update check.
  282.    * @param   update
  283.    *          A nsIUpdate object that contains details about the 
  284.    *          error in its |statusText| property.
  285.    */
  286.   void onError(in nsIXMLHttpRequest request,
  287.                in nsIUpdate update);
  288. };
  289.  
  290. /**
  291.  * An interface describing an object that knows how to check for updates.
  292.  */
  293. [scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)]
  294. interface nsIUpdateChecker : nsISupports
  295. {
  296.   /**
  297.    * Checks for available updates, notifying a listener of the results.
  298.    * @param   listener
  299.    *          An object implementing nsIUpdateCheckListener which is notified
  300.    *          of the results of an update check.
  301.    * @param   force
  302.    *          Forces the checker to check for updates, regardless of the 
  303.    *          current value of the user's update settings. This is used by
  304.    *          any piece of UI that offers the user the imperative option to
  305.    *          check for updates now, regardless of their update settings.
  306.    *          force will not work if the system administrator has locked
  307.    *          the app.update.enabled preference.
  308.    */
  309.   void checkForUpdates(in nsIUpdateCheckListener listener, in boolean force);
  310.  
  311.   /**
  312.    * Constants for the |stopChecking| function that tell the Checker how long
  313.    * to stop checking:
  314.    * 
  315.    * CURRENT_CHECK:     Stops the current (active) check only
  316.    * CURRENT_SESSION:   Stops all checking for the current session
  317.    * ANY_CHECKS:        Stops all checking, any session from now on
  318.    *                    (disables update checking preferences)
  319.    */
  320.   const unsigned short CURRENT_CHECK    = 1;
  321.   const unsigned short CURRENT_SESSION  = 2;
  322.   const unsigned short ANY_CHECKS       = 3;
  323.  
  324.   /**
  325.    * Ends any pending update check.
  326.    * @param   duration
  327.    *          A value representing the set of checks to stop doing.
  328.    */
  329.   void stopChecking(in unsigned short duration);
  330. };
  331.  
  332. /**
  333.  * An interface describing a global application service that handles performing
  334.  * background update checks and provides utilities for selecting and 
  335.  * downloading update patches.
  336.  */
  337. [scriptable, uuid(9849c4bf-5197-4d22-baa8-e3b44a1703d2)]
  338. interface nsIApplicationUpdateService : nsISupports
  339. {
  340.   /**
  341.    * The Update Checker used for background update checking.
  342.    */
  343.   readonly attribute nsIUpdateChecker backgroundChecker;
  344.  
  345.   /**
  346.    * Selects the best update to install from a list of available updates.
  347.    * @param   updates
  348.    *          An array of updates that are available
  349.    * @param   updateCount
  350.    *          The length of the |updates| array
  351.    */
  352.   nsIUpdate selectUpdate([array, size_is(updateCount)] in nsIUpdate updates,
  353.                          in unsigned long updateCount);
  354.  
  355.   /**
  356.    * Adds a listener that receives progress and state information about the 
  357.    * update that is currently being downloaded, e.g. to update a user 
  358.    * interface.
  359.    * @param   listener
  360.    *          An object implementing nsIRequestObserver and optionally
  361.    *          nsIProgressEventSink that is to be notified of state and
  362.    *          progress information as the update is downloaded.
  363.    */
  364.   void addDownloadListener(in nsIRequestObserver listener);
  365.  
  366.   /**
  367.    * Removes a listener that is receiving progress and state information
  368.    * about the update that is currently being downloaded. 
  369.    * @param   listener
  370.    *          The listener object to remove.
  371.    */
  372.   void removeDownloadListener(in nsIRequestObserver listener);
  373.  
  374.   /**
  375.    * 
  376.    */
  377.   AString downloadUpdate(in nsIUpdate update, in boolean background);
  378.  
  379.   /**
  380.    * Pauses the active update download process
  381.    */
  382.   void pauseDownload();
  383.  
  384.   /**
  385.    * Whether or not there is an download happening at the moment.
  386.    */
  387.   readonly attribute boolean isDownloading;
  388.  
  389.   /**
  390.    * Whether or not the Update Service can download and install updates.
  391.    * This is a function of whether or not the current user has access 
  392.    * privileges to the install directory.
  393.    */
  394.   readonly attribute boolean canUpdate;
  395. };
  396.  
  397. /**
  398.  * An interface describing a global application service that maintains a list
  399.  * of updates previously performed as well as the current active update. 
  400.  */
  401. [scriptable, uuid(fede66a9-9f96-4507-a22a-775ee885577e)]
  402. interface nsIUpdateManager : nsISupports
  403. {
  404.   /**
  405.    * Gets the update at the specified index
  406.    * @param   index
  407.    *          The index within the updates array
  408.    * @returns The nsIUpdate object at the specified index
  409.    */
  410.   nsIUpdate getUpdateAt(in long index);
  411.  
  412.   /**
  413.    * Gets the total number of updates in the history list. 
  414.    */
  415.   readonly attribute long updateCount;
  416.  
  417.   /**
  418.    * The active (current) update. The active update is not in the history list.
  419.    */
  420.   attribute nsIUpdate activeUpdate;
  421.  
  422.   /**
  423.    * Saves all updates to disk. 
  424.    */
  425.   void saveUpdates();
  426. };
  427.  
  428. /**
  429.  * An interface describing an object that can show various kinds of Update 
  430.  * notification UI to the user. 
  431.  */
  432. [scriptable, uuid(22b00276-ec23-4034-a764-395da539b4be)]
  433. interface nsIUpdatePrompt : nsISupports
  434. {
  435.   /**
  436.    * Shows a user interface that checks for and then displays the available
  437.    * updates.
  438.    */
  439.   void checkForUpdates();
  440.  
  441.   /**
  442.    * Show a message advising that an update is available for download and
  443.    * install.
  444.    * @param   update
  445.    *          The update to be downloaded and installed
  446.    */
  447.   void showUpdateAvailable(in nsIUpdate update);
  448.  
  449.   /**
  450.    * Show a message advising that an update has now been downloaded and that
  451.    * the user should restart their software should be restarted so that the
  452.    * update can be installed.
  453.    * @param   update
  454.    *          The update that was downloaded
  455.    */
  456.   void showUpdateDownloaded(in nsIUpdate update);
  457.  
  458.   /**
  459.    * Shows a message detailing the update which was installed.
  460.    * @param   update
  461.    *          The nsIUpdate object which was just installed
  462.    */
  463.   void showUpdateInstalled(in nsIUpdate update);
  464.  
  465.   /**
  466.    * Shows an error message UI telling the user about some kind of update
  467.    * failure, e.g. failure to apply patch.
  468.    * @param   update
  469.    *          The nsIUpdate object which we could not install
  470.    */
  471.   void showUpdateError(in nsIUpdate update);
  472.  
  473.   /**
  474.    * Shows a list of all updates installed to date.
  475.    * @param   parent
  476.    *          A parent window to anchor this window to. Can be null.
  477.    */
  478.   void showUpdateHistory(in nsIDOMWindow parent);
  479. };
  480.  
  481. /**
  482.  * An interface describing a global application service that allows long 
  483.  * duration (e.g. 1-7 or more days, weeks or months) timers to be registered
  484.  * and then fired. 
  485.  */
  486. [scriptable, uuid(0765c92c-6145-4253-9db4-594d8023087e)]
  487. interface nsIUpdateTimerManager : nsISupports
  488. {
  489.   /**
  490.    * Register an interval with the timer manager. The timer manager 
  491.    * periodically checks to see if the interval has expired and if it has
  492.    * calls the specified callback. This is persistent across application
  493.    * restarts and can handle intervals of long durations.
  494.    * @param   id
  495.    *          An id that identifies the interval, used for persistence
  496.    * @param   callback
  497.    *          A nsITimerCallback object that is notified when the interval
  498.    *          expires
  499.    * @param   interval
  500.    *          The length of time, in milliseconds, of the interval
  501.    */
  502.   void registerTimer(in AString id, 
  503.                      in nsITimerCallback callback, 
  504.                      in unsigned long interval);
  505. };
  506.